<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<!--  
     Copyright  2009  Sun Microsystems, Inc. All rights reserved.
-->
<HTML>
<HEAD>
	<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
	<TITLE></TITLE>
	<META NAME="GENERATOR" CONTENT="StarOffice 7  (Solaris Sparc)">
	<META NAME="CREATED" CONTENT="20040305;17001400">
	<META NAME="CHANGED" CONTENT="20040405;18210300">
	<!-- Changed  07-Mar-2005 -->
	<STYLE>
	<!--
		@page { size: 8.5in 11in }
	-->
	</STYLE>
</HEAD>
<BODY LANG="en-US" DIR="LTR">
<P>The Content Handler API is specified to integrate with the
application management framework of either CLDC/MIDP or CDC/PBP. This
design is for the integration with CLDC/MIDP in the MIDP stack project.
The design will work with either Single or Multiple VM
implementations of the VM . Part of the adaptation will be in CHAPI and
part in the MIDP stack multi-tasking APIs.</P>
<P>The purpose of the Content Handler API is allow a seamless user
experience between applications that are displaying content. For
example, a browser may contain a link to an address book entry
(VCard) when the user follows the link the browser is terminated and
the address book application is started with the URL in the link. The
invoking application uses CHAPI to dispatch to the appropriate
application and the integration with the AMS provides the mechanism
to launch the appropriate content handler. The content handler
fetches the content and displays it to the user.</P>
<P>The seamlessness of the content handler is enhanced with the
provision to guide the user through the installation of an
appropriate content handler, if one is not present on the device. The
application discovery application and installation applications are
the content handlers for MIDlet suites JAD and JARs.</P>
<H2>Table of Contents</H2>
<UL>
	<LI><P STYLE="margin-bottom: 0in"><A HREF="#name">Functionality</A> 
	</P>
	<LI><P STYLE="margin-bottom: 0in"><A HREF="#specification">Specification</A></P>
	<LI><P STYLE="margin-bottom: 0in"><A HREF="#unittest">Unit Testing</A></P>
	<LI><P STYLE="margin-bottom: 0in"><A HREF="#example">Examples</A></P>
	<LI><P STYLE="margin-bottom: 0in"><A HREF="#UserExperience">User
	Experience Requirements</A></P>
	<LI><P STYLE="margin-bottom: 0in"><A HREF="#design">Design</A></P>
</UL>
<H2><A NAME="function"></A>CHAPI Functionality</H2>
<P>CHAPI provides a number of high level functions as a direct result
of implementing the specification. The detailed list of functions of
the implementation are listed in the {@link com.sun.content.test
Introduction to the Unit Tests} that have been developed with the
implementation.</P>
<UL>
	<LI><P STYLE="margin-bottom: 0in">Support for Java invocation of
	Java content handlers</P>
	<LI><P STYLE="margin-bottom: 0in">Support for native invoking Java
	content handlers (Not Phase 1)</P>
	<LI><P STYLE="margin-bottom: 0in">Support for Java invoking native
	content handlers (Not Phase 1)</P>
	<LI><P STYLE="margin-bottom: 0in">Caching of content by invoking
	Java application, read by Java content handler</P>
</UL>
<H2>Dependencies</H2>
<UL>
	<LI><P STYLE="margin-bottom: 0in">MVM re-architecture</P>
	<LI><P STYLE="margin-bottom: 0in">AMS interfaces for MIDletSuite
	installation and removal</P>
	<LI><P STYLE="margin-bottom: 0in">Event Interfaces</P>
</UL>
<H2><A NAME="specification"></A>CHAPI Specification</H2>
<P>The specification a separate pdf that defines the formal
specification. The <A HREF="spec-overview.html">overview</A> and
package documentation for the package {@link
javax.microedition.content} is identical to the official
specification.</P>
<H2><A NAME="unittest"></A>CHAPI Unit Testing</H2>
<P>The CHAPI unit testing is described in the package {@link
com.sun.content.test}.</P>
<H2><A NAME="example;"></A>CHAPI Example Applications</H2>
<P>The example programs used for demonstrations or for simple code
samples are found in the packages {@link example.text} and
{@link example.browser}.</P>
<H2><A NAME="UserExperience"></A>User Experience Requirements</H2>
<P>CHAPI has a number of new elements that require changes to the
User Experience of MIDP stack.</P>
<H3>Installation:</H3>
<UL>
	<LI><P>A new permission is added to restrict which MIDlet suites can
	be installed as ContentHandlers.</P>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">New permissions require new
		messages in the ResourceConstants.java and LocalizedStrings.java
		files.</P>
		<LI><P STYLE="margin-bottom: 0in">Title: &quot;OK to register
		application?&quot;</P>
		<LI><P STYLE="margin-bottom: 0in">Question: &quot;%1 wants to
		register as a content handler. Is this OK?&quot;</P>
	</UL>
	<LI><P>Content handler specific attributes are added to the
	application descriptor file and they may be formatted incorrectly
	resulting in errors that prevent installation. Just as with other
	application descriptor attribute problems there is not much that can
	be said in terms the user would understand. The current message is:
	&ldquo;&quot;%1 cannot be installed because critical information is
	not formatted correctly or is invalid. Contact your application
	provider to correct this situation.&rdquo; I recommend that the same
	message be used. 
	</P>
	<LI><P STYLE="margin-bottom: 0in">Content handler applications are
	registering for content types. It is possible that the requested
	types, names or suffixes are already registered to another content
	handler application. It is possible to identify the specific (MIME)
	types that conflict and the other application that have them
	reserved. However, the detailed type information is not meaningful
	to phone users. Probably the most useful message would only identify
	that the new application requires the same resources as an existing
	application and that it would need to be removed before the new
	application can be installed.</P>
</UL>
<H3>Dynamic Content Handler Download</H3>
<P STYLE="margin-bottom: 0in">Content handlers can be installed on
demand when they are first referenced. The installation process can
be transparent to the application but will not be transparent to the
user. The bulk of the installation process is identical to that for
any MIDlet suite. The steps are outlined below:</P>
<OL>
	<OL>
		<LI><P STYLE="margin-bottom: 0in">Prompt the user to say that no
		content handler in installed for type &lt;x&gt; and asking if one
		should be located. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">Query a pre-configured
		provisioning server with the type of the content handler needed. If
		the provisioning server returns an error, inform the user and
		return a failure to the application. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">Prompt the user to ask if the
		content handler application should be installed.&nbsp; This is the
		same as the current installer question. If the user says NO, then
		return a failure to the application. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">Install the application following
		the current dialogs for size, etc. during installation. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">Prompt to indicate the
		installation is done. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">Return to the normal processing
		which will invoke the just installed content handler.</P>
	</OL>
</OL>
<P STYLE="margin-bottom: 0in">Through some kind of policy or user
choice I'd like to see the minimum number of prompts to speed the
user through the process. I could see two modes:</P>
<UL>
	<UL>
		<LI><P STYLE="margin-bottom: 0in">Fully automatic: No prompts are
		given, only the progress of the installation is shown. Failures due
		to size, etc do interrupt the user experience so the user knows why
		it failed (but may not be able to do anything). <BR>The prompts in
		steps 1, 3, 5 are not performed. 
		</P>
		<LI><P STYLE="margin-bottom: 0in">Confirm: Only Prompt 3 is used to
		allow the user to confirm installation of the content handler. This
		the most informative and provides the user the control over the
		installed applications. <BR>Prompts 1 and 5 are not used. 
		</P>
	</UL>
</UL>
<H3>Seamless User Interface Transitions</H3>
<P>When an application invokes a ContentHandler, the transition of
the user interface display from the invoking application to the
invoked application must be managed carefully to provide a seamless
user experience.  The display manager and application manager must be
implemented to avoid extra prompts during transitions.</P>
<H2>Integration with MIDP stack</H2>
<P>This section describes the integration with the MIDP
implementation.</P>
<P>There are NO platform dependent components to the implementation.</P>
<P>Parts of the MIDP workspace will need to be modified to
support integration of CHAPI.</P>
<P>The modifications will allow the MIDP workspace to built with
and without CHAPI.</P>
<P>The CHAPI specification and implementation are maintained in a
separate workspace. However, this workspace depends heavily on the
MIDP stack workspace.</P>
<TABLE WIDTH=100% BORDER=1 CELLPADDING=4 CELLSPACING=3>
	<COL WIDTH=110*>
	<COL WIDTH=146*>
	<THEAD>
		<TR VALIGN=TOP>
			<TH WIDTH=43%>
				<P>Files/Config</P>
			</TH>
			<TH WIDTH=57%>
				<P>Modifications</P>
			</TH>
		</TR>
	</THEAD>
	<TBODY>
		<TR VALIGN=TOP>
			<TD WIDTH=43%>
				<P>USE_CHAPI=true</P>
			</TD>
			<TD WIDTH=57%>
				<P>To configure CHAPI into the BUILD</P>
			</TD>
		</TR>
		<TR VALIGN=TOP>
			<TD WIDTH=43%>
				<P>CHAPI_DIR=&lt;chapi_ws&gt;</P>
			</TD>
			<TD WIDTH=57%>
				<P>The directory containing the CHAPI workspace</P>
			</TD>
		</TR>
		<TR VALIGN=TOP>
			<TD WIDTH=43%>
				<P>/src/chapi/config/modules.cfg</P>
			</TD>
			<TD WIDTH=57%>
				<P>The additional files needed when CHAPI is included</P>
			</TD>
		</TR>
		<TR VALIGN=TOP>
			<TD WIDTH=43%>
				<P>com/sun/midp/security/Permissions.java</P>
			</TD>
			<TD WIDTH=57%>
				<P>New Permission<BR>javax.microedition.content.ContentHandler</P>
			</TD>
		</TR>
		<TR VALIGN=TOP>
			<TD WIDTH=43%>
				<P>com/sun/midp/installer/Installer<BR>com/sun/midp/installer/GraphicalInstaller<BR>com/sun/midp/installer/InvalidJadException<BR>com/sun/midp/io/Util<BR>com/sun/midp/i18n/ResourceConstants<BR>com/sun/midp/l10n/LocalizedStrings</P>
			</TD>
			<TD WIDTH=57%>
				<P>Hooks are added to call the ContentHandler preinstall,
				install, and restore methods<BR>Added exception reason for
				invalid content handlers<BR>Generalized some parsing methods in
				Util<BR>Added install constants and messages</P>
			</TD>
		</TR>
	</TBODY>
</TABLE>
<P><BR><BR>
</P>
<H2><A NAME="design"></A>CHAPI Design</H2>
<H3>Single vs Multiple VM mode</H3>
<P>Single VM mode corresponds to the sequential execution of
applications that is necessary when using a KVM VM that can support
only a single application at a time. When a new application is
invoked the current application must terminate first. The invocation
queues will be implemented in native memory instead of files since
the native memory will be stable across VM restarts. In the case
where there are native APIs to perform invocations the queues will
need to be in a stable state when the VM is suspended.</P>
<P>Multiple VM Mode uses the ability of the VM to support multiple
applications concurrently. Instead of having to stop and VM and
restart it to run the next application, the next application is
started without stopping the invoking application. With current use
of native applications and a native environment that cannot support
both the VM and a native application running concurrently it
technique may be necessary to allow the VM to be suspended (no
bytecode execution). In the case where there are native APIs to
perform invocations the queues will need to be in a stable state when
the VM is suspended.</P>
<H3>Content Handler Registry</H3>
<P>The Content Handler Registry is a persistent store of all of the
content handler registration attributes. It is stored in a file using
the Storage component. The file is stored in the <CODE>appdb</CODE>
directory along with the other files. The persistent store is updated
atomically with each call to the ContentHandler register or
unregister method.</P>
<P>The public {@link javax.microedition.content.ContentHandler} class
delegates most functions to the {@link com.sun.midp.content.RegistryImpl}
class. The Registry uses a singleton instance as the only access to
the registry. A security token with the &ldquo;MIDP&rdquo; permission
is required to get the Registry.</P>
<P>The details of the Registry functions and design is described in
the {@link com.sun.midp.content.RegistryImpl} class.</P>
<H3>Application Installation</H3>
<P>During installation of a MIDlet suite the {@link
com.sun.midp.installer.Installer} checks for the presence of the
content handler attributes and invokes the preinstall, install and
restore methods of {@link com.sun.midp.content.CHManagerImpl
CHManagerImpl} to perform the additional steps. It will parse the
attributes and assemble the set of registrations needed for the
suite. The {@link com.sun.midp.content.CHManagerImpl#preInstall
preInstall} method checks for proper syntax of the attributes and
checks for conflicts with other MIDlet suites. In the {@link
com.sun.midp.content.CHManagerImpl#install install} method the old
registrations for the suite, if any, are removed and the new
registrations are made. If the registration fails for some reason
after that point the {@link
com.sun.midp.content.CHManagerImpl#restore restore} method is used
to restore the MIDlet suite's previous registations.</P>
<H3>Application Invocation</H3>
<P>The queue of pending invocations is maintained for each
application. Logically, there is a queue for each target content
handler. Each invocation identifies the transaction it is part of,
the invoking application and the target of the invocation along with
the type and arguments.</P>
<P><BR><BR>
</P>
<H3>Queuing of Invocations</H3>
<P>Tbd:</P>
<H3>MIDletSuiteStorage</H3>
<P>The storage for the Content Handler Registry is provided by the
MIDletSuiteStorage class. When a suite is removed all of its
registered handlers are removed also. 
</P>
</BODY>
</HTML>
